home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Internet Tools 1995 April / Internet Tools.iso / dos_win / winsock / maillist / 94-04.Z / 94-04 / text0130.txt < prev    next >
Encoding:
Text File  |  1994-04-30  |  8.0 KB  |  178 lines
  1.                  ADDING USER-DEFINED EXTENSIONS TO WCL
  2.                  -------------------------------------
  3. Over the past few months, I have received incessant requests for me to
  4. provide support for user extensions to my command line processor for Windows
  5. (WCL) - some people want to implement a telnetd for winsock, using WCL as
  6. the basic CLI, and others just want to be able to extend the command set.
  7. I have finally decided to provide a limited interface or hook to WCL
  8. for Windows programmers so that they can add their own commands. This
  9. provides endless opportunities for extending the command set which I have
  10. provided as internal commands, since such user extensions are treated as
  11. internal commands by WCL.
  12.  
  13. I explain the basic structure of the interface below. I have decided as
  14. a preliminary measure to make a working copy of the beta shareware
  15. version available to programmers who want to have a look at the interface
  16. I have provided. This consists only of BIGWCL.EXE and the files needed
  17. to make it work, plus the documentation for the interface I have provided.
  18. If you are interested, and can receive a large UUencoded file (305kb)
  19. then you can e-mail me. I will send a copy to the first 20 respondents.
  20. If you hear nothing from me, then please assume that you were not among
  21. the first 20 replies I received - sorry, but I cannot reply to every one
  22. and I will not make this more publicly available, since this feature is
  23. still only at a beta stage. Whether I will go on and add this feature to the
  24. release versions depends entirely on the feedback I receive.
  25.  
  26. Please note that the standard shareware restrictions apply to anything I
  27. send to anybody. You can test it for 30 days. After that, you are required
  28. to please register it, or delete it from your disks. The only thing that
  29. is beta in it is this interface I am trying to provide for programmers.
  30.  
  31. The interface
  32. -------------
  33. The interface I have provided is very simple, as long as the rules are
  34. adhered to. It revolves around a DLL which must be created by the user, and
  35. which exports only 1 function (actually, it can export as many functions as
  36. it likes, but WCL will refer to only ONE named function).
  37.  
  38. Rules
  39. -----
  40. 1. The DLL must be called WCL_EXT.DLL, and must be compiled with the FAR
  41.    directive (and for C/C++ programmers, it must be "FAR Pascal").
  42. 2. The function which WCL will interface to takes a null terminated string
  43.    as the ONLY parameter, and returns an INTEGER. It must be defined,
  44.    EXACTLY thus;
  45.  
  46.      [a] In Borland PASCAL
  47.           Function UserProc (Var Parm : PChar) : Integer;
  48.      [b] In C/C++
  49.           int UserProc (LPSTR Parm);   (or is it *Parm)?
  50.  
  51.    I don't have a clue as to how you will do this in VBasic. If anyone
  52.    knows, please do let me know.
  53.  
  54. 3. In the EXPORTS section of the DLL, the function must be given an ordinal
  55.    index number of 1
  56.  
  57.    eg, in Pascal
  58.        exports
  59.        UserProc index 1;
  60.  
  61. 4. You cannot do any output to the WCL window in your DLL (i.e., no
  62.    Writeln() in Pascal or output to STDOUT in C/C++) - all communications
  63.    with the user during the operation of your functions must be by Windows
  64.    dialog boxes.
  65. 5. If you want the output from the commands to be echoed in the WCL window,
  66.    you have to do 2 things;
  67.        [a] Let function UserProc return ZERO or higher
  68.        [b] Put whatever you want to be output at the WCL window into the
  69.            null terminated string that was passed as a parameter to
  70.            UserProc
  71.  
  72.    If the function returns 0 or higher, WCL will re-direct whatever it finds
  73.    in "Parm" to the WCL window, when your function returns. Note that the
  74.    output in the string is dumped to the WCL window exactly as it is. If you
  75.    want a formatted output, you have to format the null terminated string
  76.    yourself, in your function (eg by inserting carriage returns after every
  77.    60 characters).
  78.  
  79.    If the function returns a value less than 0 (eg -1) then nothing will be
  80.    written to the WCL window.
  81.  
  82. 6. When you want to call one of your user defined commands, you type
  83.    "EXT" or "USERPROC" at the WCL prompt, followed by your own commands.
  84.    Prefixing "EXT" to a command is the way to tell WCL to pass on the
  85.    command to your user defined function. When WCL finds "EXT" or
  86.    "USERPROC", it will pass whatever appears afterward to your DLL,
  87.    exactly as it appears.
  88.  
  89.    e.g, if you have a new command "MYPROG", to call it, you would type
  90.      "EXT MYPROG" from the WCL prompt.
  91.  
  92. Comments
  93. --------
  94. I have decided to use this method of providing hooks for other programmers
  95. for a number of reasons. First, it is straightforward. Secondly, it does not
  96. add much to the bulk of WCL itself - something I have to take seriously,
  97. because most of my users are not programmers and are not interested in this
  98. feature.
  99.  
  100. I expect the function UserProc() to be used as a "container" or "interface"
  101. function only - although you can use it as you please. What I really
  102. envisage is that programmers can define any number of functions and commands
  103. in their WCL_EXT.DLL, and that they will use the function UserProc() as
  104. their "command line", which they will then parse, and then call other
  105. functions in the DLL or elsewhere as may be necessary. Check this pseudo
  106. code;
  107.  
  108. {------------------------------------------------------------}
  109.     function UserProc (Var Parm : PChar) : integer;
  110.     begin UserProc
  111.  
  112.         if Parm = "SHUTDOWN" then call function ONE
  113.         else
  114.         if Parm = "OK" then call function TWO
  115.         else
  116.         if Parm = "MAKE_NOISE" then call MessageBeep (0)
  117.         else
  118.         {etc, etc, etc }
  119.  
  120.         Return -1
  121.     end UserProc
  122. {-----------------------------------------------------------}
  123.  
  124. For those programmers who need it, I have provided an interface to a number
  125. of functions in WCLCODE2.DLL, which comes standard with WCL. These are
  126. string functions - to break up the "Parm" string parameter into as many
  127. substrings as are found in it (up to 20) and return the number of such
  128. substrings. This way, it is easy to parse the parameter passed to the
  129. UserProc function.
  130.  
  131. eg if you passed "BPC -CW MYPROG.PAS /$F+ /L /$N+" in "Parm", calling the
  132. function BreakString() will return 6 (there are 6 substrings in this string)
  133. and the 6 substrings will be returned in an array.
  134.  
  135. These string functions were originally written to process Pascal type
  136. strings only, but I have added equivalents for null terminated strings so
  137. that C/C++ users can use the same functions. I have provided a Borland
  138. Pascal interface unit (WCL_INT.PAS) for these functions, which contains all
  139. the declarations, and the ordinal numbers of the functions, etc. Pascal
  140. programmers can just add this unit to their USES clause, and start using the
  141. functions right away. C/C++ programmers will have to create a header file
  142. using the supplied information, and also a LIB file for WCLCODE2.DLL, using
  143. their compiler's IMPLIB utility. If anybody does this successfully, please
  144. send me a copy of the header file, and of the LIB file (indicating what
  145. compiler this was created for).
  146.  
  147. As for VBasic programmers - sorry, I don't have a clue as to how you would
  148. go about using these functions.
  149.  
  150. I have also provided a sample WCL_EXT.DLL, with the Pascal source code to it
  151. (WCL_EXT.PAS), which uses the parsing functions I referred to above. This is
  152. supplied just as an example - to see what types of things you could do in
  153. your DLL - but also because I need to provide a dummy DLL of that name,
  154. since WCL now contains a reference to WCL_EXT.DLL.
  155.  
  156. When you create your own DLL, just copy it over the one that is supplied.
  157.  
  158. Thanks for your attention and bye.
  159.  
  160. --
  161. The Chief
  162. ---------
  163. Dr. Abimbola Olowofoyeku ( The African Chief)
  164. Keele University         ( All opinions are *not* personal and *do*)
  165. England.             ( reflect the views of the whole world.)
  166.  
  167. Email: laa12@keele.ac.uk
  168.        chief@mep.com
  169.  
  170. Tel  : (0782) 621111
  171. Fax  : (0782) 583228
  172. ---------------------------------------------------
  173. "Do you see a man that is wise in his own conceit?      
  174. There is more hope for a fool than for him."
  175.                                       King Solomon.
  176. ---------------------------------------------------
  177.  
  178.